| Syntax | Description |
|---|---|
| %title% | Title of the track. If “title” metadata field is missing, file name is used instead. |
| %artist% | Name of the artist of the track. Checks following metadata fields, in this order: “artist”, “album artist”, “composer”, “performer”. |
| %album artist% | Name of the artist of the album specified track belongs to. Checks following metadata fields, in this order: “album artist”, “artist”, “composer”, “performer”. The difference between this and %artist% is that %album artist% is intended for use where consistent value across entire album is needed even when per-track artists values vary. |
| %track artist% | Name of the artist of the track; present only if %album artist% is different than %artist% for specific track. Intended for use together with %album artist%, to indicate track-specific artist info, e.g. “%album artist% - %title%[ '//' %track artist%]” - in this case, last part will be displayed only when track-specific artist info is present. |
| %album% | Name of the album specified track belongs to. Checks following metadata fields, in this order: “album”, “venue”. |
| %date% | Recording date (year) of the album specified track belongs to, using “date” metadata field. |
| %genre% | Genre of the album specified track belongs to, using “genre” metadata field. |
| %tracknumber% | Two-digit index of specified track within the album. Available only when “tracknumber” field is present in track’s metadata. |
| %totaltracks% | Two-digit number of tracks within the album specified track belongs to. Available only when “totaltracks” field is present in track’s metadata. |
| %discnumber% | Index of disc specified track belongs to, within the album. Available only when “discnumber”/”disc” field is present in track’s metadata |
| %totaldiscs% | Number of discs within the album specified track belongs to. Available only when “totaldiscs” field is present in track’s metadata. |
| %codec% | Name of codec used to encode the track. If exact codec name is not available, file extension is used. |
| %codec_profile% | Additional information about encoding settings used. Not always available. |
| %filename% | Name of file, excluding directory path and extension. |
| %filename_ext% | Name of the file, including extension but excluding directory path. |
| %directoryname% | Name of the directory the file is in. |
| %path% | Full path of the file. Note that %path_sort% should be use for sorting instead of %path%. |
| %subsong% | Index of the track within the file, for use with file formats that support multiple tracks within single physical file (e.g. chapters or a cuesheet). |
| %path_sort% | Path of the file; for use with sorting, where order of subsongs within a file needs to be preserved; exact value returned by it is undefined and should not be relied on. |
| %length% | Length of the track, formatted as [HH:]MM:SS. |
| %length_seconds% | Length of the track, in seconds, formatted as an integer. |
| %bitrate% | Bitrate of the track; includes dynamic VBR bitrate display for currently played track. |
| %channels% | Number of channels in the track (mono/stereo/etc). |
| %samplerate% | Sample rate of the track, in Hz. |
The above list is not complete, there are other less relevant fields as well as generic %field% ⇒ metadata and %__field% ⇒ tech info remappings provided for backwards compatibility.
| Syntax | Description |
|---|---|
| %list_index% | Index of the item on the list it belongs to. Applies to: playlist, list of items processed by masstagger/massrenamer, etc. Padded with zeros to match max. width of possible index within the list. |
| %list_total% | Number of items on the list specified item belongs to. Applies to: playlist, list of items processed by masstagger/massrenamer, etc. |
| %isplaying% | Present if e.g. a playlist item is currently being played, absent otherwise. Meant to be used as a switch for $if(). |
| %ispaused% | Present if e.g. a playlist item is currently being played and is paused, absent otherwise. Meant to be used as a switch for $if(). |
| %playback_time% | Current playback time, formatted as [HH:]MM:SS. Available only in contexts where playback related data is displayed, such as statusbar, as well as in playlist (present only for currently played track). |
| %playback_time_seconds% | Current playback time, in seconds, formatted as integer. Available only in contexts where playback related data is displayed, such as statusbar, as well as in playlist (present only for currently played track). |
| %playback_time_remaining% | Remaining playback time, formatted as [HH:]MM:SS. Available only in contexts where playback related data is displayed, such as statusbar, as well as in playlist (present only for currently played track). Not available when length of currently playing track is not known. |
| %playback_time_remaining_seconds% | Remaining playback time, in seconds, formatted as integer. Available only in contexts where playback related data is displayed, such as statusbar, as well as in playlist (present only for currently played track). Not available when length of currently playing track is not known. |
| Syntax | Description | Example |
|---|---|---|
| $abbr(X) | Returns an abbreviation of X. | $abbr(%album%) |
| $abbr(X,Y) | Returns an abbreviation of X if X is longer than Y characters; otherwise returns full value of X. | %abbr(%album%,5) |
| $lower(X), $upper(X) | Converts X to lower/uppercase. | $upper(%title%) |
| $num(X,Y) | Displays X as a number and pads with zeros up to Y characters (useful for track numbers etc). | $num(%tracknumber%,3) |
| $caps(X) | Converts first letter in every word of X to uppercase, and all other letters to lowercase, e.g. “blah BLAH”→“Blah Blah”. | $caps(%title%) |
| $caps2(X) | Similar to $caps, but leaves uppercase letters as they are, e.g. “blah BLAH”→“Blah BLAH”. | $caps2(%title%) |
| $if(X,Y,Z) | If X contains at least one present field, executes/displays Y, otherwise executes/displays Z. | $if(%artist%,%artist%,unknown artist) |
| $if2(X,Y) | Same as $if(X,X,Y). | |
| $if3(X,Y,Z,..) | Returns first of parameters that contains at least one present field. | |
| $ifgreater(A,B,C,D) | If number A is greater than number B, executes/returns C, otherwise executes/returns D. | |
| $iflonger(A,B,C,D) | If string A is longer than B characters, executes/returns C, otherwise executes/returns D. | |
| $longest(A,B,C,....) | Compares lengths of of A,B,C... and returns the longest one. | $longest(%title%,%filename%) |
| $len(X) | Returns length of the string X in characters. | |
| $pad(X,Y), $pad_right(X,Y) | Pads X with spaces up to Y characters. | |
| $pad(X,Y,Z), $pad_right(X,Y,Z) | Pads X with Z character up to Y characters. | |
| $cut(X,Y) | Truncates X to Y characters. | |
| $padcut(X,Y), $padcut_right(X,Y) | Pads X to Y characters and truncates to Y if longer. | |
| $insert(A,B,N) | Inserts string B into string A after N characters. | |
| $add(X,Y), $sub(X,Y), $mul(X,Y), $div(X,Y), $mod(X,Y), $min(X,Y), $max(X,Y) | Various math operations. | |
| $left(X,Y) | Returns Y first characters of string X. | |
| $right(X,Y) | Returns Y last characters of string X. | |
| $and(X,Y), $or(X,Y), $xor(X,Y), $not(X) | Various logical operations, for use with $if(). | |
| $fix_eol(x), $fix_eol(x,y) | Truncates multiline strings, adding ” (...)” (version 1) or y (version 2) at the end. | |
| $meta(X) | Returns value of metadata field named X. | $meta(artist) |
| $meta_sep(X,Y), $meta_sep(X,Y,Z) | Returns metadata field named X, with custom separators for multiple values | $meta(artist,', ',' and ')⇒“artist1, artist2 and artist3” |
| $meta_num(X) | Inserts number of present values for metadata field X. | |
| $info(X) | Returns tech info field named X. | $info(bitrate) |
| $char(X) | Inserts Unicode character no. X. | $char(9674) |
| $strcmp(X,Y) | Returns “1” when strings X and Y are identical, empty string otherwise; intended for use with $if(). | |
| $stricmp(X,Y) | Non-case-sensitive version of $strcmp(X,Y). | |
| $directory(X), $directory(X,N) | Extracts directory name from file path X, optionally goes up by N directory levels. | $directory(%path%,2) |
| $greater(X,Y) | Compares two integers, tests if X>Y, intended for use with $if() and logical operators. | |
| $longer(X,Y) | Compares two strings, tests if X is longer than Y, intended for use with $if() and logical operators. | |
| $strchr(X,Y) | Finds first occurrence of character Y in string X. | |
| $strrchr(X,Y) | Finds last occurrence of character Y in string X. | |
| $strstr(X,Y) | Finds first occurrence of string Y in string X. | |
| $progress(A,B,C,D,E) | Creates a progress bar. | $progress(%playback_time_seconds%,%length_seconds%,20,’#’,’=’) ⇒“====#===============” |
| $progress2(A,B,C,D,E) | Creates a progress bar, alternate version. | $progress2(%playback_time_seconds%,%length%,20,’#’,’=’) ⇒“#####===============” |
| $select(N,A,B,C,....) | Returns N-th of A,B,C... parameters. | |
| $repeat(X,N) | Repeats X N times. | |
| $replace(A,B,C) | Replaces all occurrences of string B in string A with string C. | |
| $ext(X) | Extracts extension from file path / file name. | $ext(%path%) |
| $substr(A,B,C) | Returns substring of string A, starting from B-th character and ending at C-th character | $substr(blah,1,2) ⇒“bl” |
| $rgb(), $rgb(R,G,B), $rgb(R,G,B,RS,GS,BS) | Generates a color code. Parameters are integral numbers from 0-255 range, specifying values of red/green/blue components. Zero-parameter version reverts to default colors. 6-parameter version allows you to override colors for selected items in playlist etc (by default, selection text color is inverted). Warning: $rgb should not be used as a parameter to any text-processing functions, results of doing so are undefined and may change between versions. | $rgb(255,0,0)asdf$rgb() ⇒ “asdf” |
| $transition(A,B,C) | Generates color codes between characters in string A, interpolating colors from B to C. | $transition(%title%,$rgb(255,255,255),$rgb(0,0,0)) |
| $blend(A,B,C,D) | Generates a color in C/D between colors A and B. | $blend($rgb(0,0,0),$rgb(255,255,255),50,100) |
| $rand() | Generates a random number in range from 0 to 2^32-1. | |
| $trim(A) | Trims leading/trailing spaces from A. | $trim(%title%) |
| $tab() | Generates a tab character; equivalent to $char(9). See “tab character” explanation below for more info about its use. | $tab() |
| Syntax | Description | Example |
|---|---|---|
| $put(name,text) | Sets variable named <name> to <text> and returns <text>. | “$put(x,blah)” sets variable x to “blah” and returns “blah”. |
| $puts(name,text) | Silent version of $put(). Same as $put(name,text), but returns an empty string. | |
| $get(name) | Returns value of variable <name>. | “$puts(x,blah)$get(x)$get(x)” will return “blahblah” |
| Syntax | Description | Example |
|---|---|---|
| [ .... ] | Discards contents of the bracket when no fields referenced inside are present. Commonly used to create parts of formatting scripts that are active only when relevant fields are found. | %artist% - [%album% / ]%title% |
| ' (single quotation mark) | Inserts specified text bypassing syntax processing; allows special characters such as %,$,[,] to be inserted. In order to insert a quotation mark character, use '' (two single quotation marks). | |
| // | Comments, can be placed only at the beginning of a new line; prevent any characters following them until the end of line from being parsed. | |
| End-of-line characters | Ignored; you can make your script more readable by splitting it into multiple lines, without affecting its output. | |
| Tab character | Used to control text alignment in certain contexts such as playlist or status bar; commonly used to separate left-aligned artist/album/title display from right-aligned length/time display in playlist. Can be used multiple times to generate pseudo-columns. See also: $tab(). | %title%$tab()%length% |